Figure.text: Allow passing a sequence of offset to the 'offset' parameter#4652
Figure.text: Allow passing a sequence of offset to the 'offset' parameter#4652seisman wants to merge 6 commits into
Conversation
seisman
added
enhancement
seisman
added
final review call
| y=[latA, latB], | ||
| text=["A", "B"], | ||
| offset="0c/0.3c", # Move text 0.2 centimeters up (y-direction) | ||
| offset=(0, 0.3), # Move text 0.3 centimeters up (y-direction) |
There was a problem hiding this comment.
Should we keep the "c" unit specifier? The gmt.conf docs say:
It is recommended that users specify the units for distances and lengths by appending c (cm), i (inch), or p (points) when changing parameters using any of these methods. By default, when no unit is specified the value will be assumed to be cm for parameters not related to fonts or pen thicknesses and will be assumed to be points for parameters related to fonts or pen thicknesses.
So recommended is to append the unit, but no unit means centimeter in some but not all cases (I guess offset counts as non-font/pen thickness?). Maybe keep it as ("0c", "0.3c") to be clearer?
There was a problem hiding this comment.
Yes, appending the unit specifier is recommended in the GMT CLI. However, in PyGMT, I feel it is more natural to use plain numbers for quantities such as offsets, widths, and sizes. They are much shorter to type and can also be used directly in calculations.
There was a problem hiding this comment.
Pull request overview
This PR updates pygmt.Figure.text to accept tuple/sequence forms for the offset parameter and migrates offset handling to PyGMT’s newer AliasSystem, with corresponding documentation and example updates.
Changes:
- Add
offsettoFigure.text’s signature and handle it viaAliasSystem(-Doption) withsep="/"andsize=2. - Update the
textdocstring to document tuple-style offsets. - Update gallery/tutorial examples to use numeric/tuple offsets instead of unit-suffixed strings.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| pygmt/src/text.py | Adds offset parameter + AliasSystem wiring for -D, and updates documentation for tuple offsets. |
| examples/tutorials/basics/text.py | Switches fig.text(..., offset=...) examples from strings (e.g., "1c/-0.5c") to tuples. |
| examples/gallery/symbols/points_cities.py | Updates offset example usage from "0.12c" to 0.12. |
| examples/gallery/lines/vector_heads_tails.py | Updates offset example usage from string to tuple. |
| examples/gallery/lines/quoted_lines.py | Updates offset example usage from string to tuple. |
| examples/gallery/lines/linestyles.py | Updates offset example usage from strings to tuples. |
| examples/gallery/lines/linefronts.py | Updates offset example usage from string to tuple. |
| examples/gallery/lines/decorated_lines.py | Updates offset example usage from string to tuple. |
| examples/gallery/images/cross_section.py | Updates offset example usage from string to tuple and adjusts the comment accordingly. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Passing a sequence of offsets to
Figure.textis frequently used but not supported yet.This PR supports it and also migrates
offsetto the new alias system.